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Prefatory Note 

Certain sections of the following reference manual are 
written in a primer -like style, especially parts of the 
introduction and the discussion of macros. However, it is 
assumed that the reader is familiar with the logical operation 
of general -purpose digital computers, and, in particular, is 
acquainted with the SDS 9*4-0 instruction set (see the SDS 
publication, SDS 9^0 Computer Reference Manual, No. 90 06 kOk, 
August, 1966, or the Project GENIE document, SDS 930 Instructions, 
Document R-27, October 11, 1966). 
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1.0 Introduction 

NARP (new ARPAS) is a one -pass assembler for the SDS 9^0 
with literal, subprogram, conditional assembly, and macro 
facilities. The source language for NARP, primarily a one-for- 
one representation of machine language written in symbolic form, 
is very similar to that for ARPAS (another assembler for the 9*1-0), 
but there are notable exceptions making it necessary to do a 
certain amount of transliteration to convert an ARPAS program to 
a NARP program. No further mention will be made of ARFkS 
in this manual; for more details see ARPAS, Reference Manual for 
Time-Sharing Assembler for the SDS 930 , Doc. No. R-26, 
February 2k, 1967. 

To motivate the various facilities of the assembler, the 
following pseudo-historical development of assembly languages 
is presented. 

1 . 1 Pseudo-history of assembly languages 

A program stored in the main memory of a modern computer 
consists of an array of tiny circular magnetic fields, some 
oriented clockwise, others oriented counterclockwise. Obviously, 
if a programmer had to think in these terms when he sat down 
to write a program, few problems of any complexity would be 
Solved by computers, and the cost of keeping programmers sane would 
be prohibitive. To remedy this situation, utility programs 
called assemblers have been developed to translate programs 
from a symbolic form convenient for human use to the rather 
tedious bit patterns that the computer handles. At first these 
assemblers were quite primitive, little more than number converters, 
in fact. Thus, for example: 



Tag Opcode Address 



76 

55 $Ml 

35 dWfe 
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would be converted into three computer instructions which would 
add together the contents of cells kM and k01 and place the 
result in cell 402. An assembler for doing this type of conver- 
sion is trivial to construct. 

After a time, some irritated programmer who could never 
remember the numerical value of the operation "load the A register 
with the contents of a cell of memory" decided that it would not 
be too difficult to write a more sophisticated assembler which 
would allow him to write a short mnemonic word in place of the 
number representing the hardware operation. Thus, the sequence 
of instructions shown above became : 

LDA 001+00 

ADD 00U01 
STA 00U02 

This innovation cost something, however, namely the assembler 
had to be more clever. But not much more clever. The programmer 
in charge of the assembler simply added a table to the assembler 
which consisted of all the mnemonic operation names ( opcodes ) 
and an associated number, namely the numerical value of the 
opcode. When a mnemonic name, say 'ADD', was encountered by the 
assembler during the conversion of a program, the opcode table 
was scanned until the mnemonic name was found; then the associated 
numerical value (in this case, 55) was used to form the instruc- 
tion. Within a month, no programmer could tell you the numerical 
value of XMA. 

In a more established field, the innovation of these mnemonic 
names would have been quite enough for many years and many 
theoretical papers. However, programmers are an irritable lot, 
and furthermore, are noted for their ability to get rid of sources 
of irritation, either by writing more clever programs or by 
asking the engineers to refrain from making such awkward machines. 
And the use of numbers to represent addresses in memory was a 
large source of irritation. To see this we need another example: 



CIA 

LDX 001*00 

2 STA 00507 

BRX 00300 
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Assuming cell kfi0 contains -7, this sequence stores zeroes in 
cells 500 through 506 provided that the sequence is loaded in 
memory so that the STA instruction is in cell 300 (otherwise, 
the BRX instruction would have to be modified). This was the 
crux of the problem: Once a program was written, it could only- 
run from a fixed place in memory and could only operate on fixed 
cells in memory. This was especially awkward when a program was 
changed, since inserting an instruction anywhere in a program would 
generally require changes in many, many addresses. One day a 
clever programmer saw that this problem could be handled by a 
generalization of the scheme used to handle opcodes, namely, 
let the programmer use symbolic names ( symbols ) for addresses 
and have the assembler build a table of these symbols as they 
are defined and then later distribute the numerical values 
associated with the symbols as they are used. Thus the example 
becomes: 

CLA 

LDX TABLEN 

LOOP STA TAEEND,2 

BRX LOOP 

(Note that at the same time the programmer decided to move 

the tag field to after the address field (simply for the sake 

of readability) and to even dispense with it entirely in case 

it was zero,) The assembler now has two tables, the fixed opcode 

table with predefined names in it, and a symbol table which is 

initially empty. There is also a special cell in the assembler 

called the location counter (LC) which keeps track of how many 

cells of program have been assembled; LC is initially zero. 

There is another complication: In the above example, when the 

symbol TABLEN is encountered, it may not be defined yet, so the 

assembler doesn't know what numerical value to replace it with. 

There are several clever ways to get around this problem, but 

the most obvious is to have the assembler process the program 

to be assembled twice . Thus, the first time the assembler scans 

the program it is mainly interested in the symbol definitions 

in the left margin (a symbol used to represent a memory address 

is called a label ) . In our example, when LOOP is encountered, 

it is stored in the symbol table and given the value 2 (because 



CIA 




LDB 


EIGHT 


LDX 


TABLEN 


STP 


TABEND,2 


EAX 


1,2 


BRX 


LOOP 
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it is preceded by two cells; remember that LC keeps track of 
this). At the end of pass 1, all symbols defined in the program 
are in the symbol table with numerical values corresponding to 
their addresses in the memory. So when pass 2 begins, the symbol 
table is used exactly as the opcode table is used, namely, when, 
for example, LOOP is encountered in the BRX instruction above, 
it is looked up in the symbol table and replaced by the value 2. 
If the program should later be changed, for example to 



LOOP 



then the assembler will automatically fix up LOOP to have the 
value 3 (because of the inserted LDB instruction) and will 
convert BRX LOOP to BRX 3 instead of to BRX 2 as before. Thus, 
the programmer can forget about adjusting a lot of numerical 
addresses and let the assembler do the work of assigning new 
values to the symbols and distributing them to the points where 
the symbols are used. In addition to the greater flexibility 
achieved, symbols with mnemonic value can be used to make the 
program more readable. 

The use of symbols to stand for numerical values which 
are computed by the assembler and not the programmer is the basic 
characteristic of all assembly languages. Its inception was 
a fundamental breakthrough in machine language programming, dispensing 
with much dullness and tedium. And a new breed of programmer 
was born: the assembler-writer. To justify his existence, the 
assembler-writer began to add all sorts of bells and whistles 
to his products; the primary ones are discussed in the next 
section (with reference to NARP) . 

1.2 Assembly languages; some basic constituents and concepts 

Times : assembly time: when a program in symbolic form is 

converted by an assembler to binary 
(relocatable) program form. 
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load time : when a binary program is converted by a loader to 
actual machine language in the main memory of 
the computer. 

rtxi time: when the loaded program is executed, 

assembler loader 
source program — > binary program ^ object program 

Expressions ; The idea of using a symbol to stand for an address 
is generalized to allow an arithmetic expression (possibly 
containing symbols) to stand for an address. Thus, some calcu- 
lations can be performed at assembly time rather than at run 
time, making programs more efficient. 

Literals : Rather than writing LDA Ml and somewhere else defining 
ML to be a cell containing -1, the literal capability allows the 
programmer to write the contents of a cell in the address field 
instead of the address of a cell. To indicate this, the expression 
is preceded by '='. The assembler automatically assigns a cell 
for the value of the expression (at the end of the program) : 

CIA 

LDB =8 

LDX «-l6*2 

LOOP STP TABBEG+l6*2,2 

EAX 1,2 

BRX LOOP 

Relocation : A relocatable program is one in which memory locations 

have been computed relative to the first word or origin of the 

program. A loader (for this assembler, DDT) can then place the 

assembled program into core beginning at whatever location may be 

specified at load time. Placement of the program involves a 

small calculation. For example, if a memory reference is to the 

nth word of a program, and if the program is loaded beginning 

at location k, the loader must transform the reference into 

absolute location n+k. This calculation should not be done to 

each word of a program since some machine instructions (shifts, 

for example) do not refer to memory locations. It is therefore 

necessary to inform the loader whether or not to relocate the 

address for each word of the program. Relocation information is 

determined automatically by the assembler and transmitted as a 

relocation factor (rf actor) . Constants or data may similarly 
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require relocation, the difference here being that the relocation 
calculation should apply to all 2k bits of the 9^0 word, not 3ust 
to the address field. The assembler accounts for this difference 
aut omat ic ally . 

Subprograms and external symbols : Programs often become quite 
large or fall into logical divisions which are almost independent. 
In either case it is convenient to break them into pieces and 
assemble (and even debug) them separately. Separately assembled 
parts of the same program are called subprograms (or packages ) . 
Before a program assembled in pieces as subprograms can be run it 
is necessary to load the pieces into memory and link them. The 
symbols used in a given subprogram are generally local to that 
subprogram. Subprograms do, however, need to refer to symbols 
defined in other subprograms. The linking process takes care of 
such cross-references. Symbols used for it are called external 
symbols . 

Directives ; A directive (pseudo-opcode is a message to the 
assembler serving to change the assembly process in some way. 
Directives are also used to create data: 





LIST 




MESSAGE 


TEXT 


'THIS IS A PIECE OF TEXT f 


START 


LDA 


ALPHA 



The LIST directive will cause the program to be listed during 
assembly, while the TEXT directive will cause the following text 
to be stored in memory, four characters to a word. 
Conditional assembly : It is frequently desirable to permit the 
assembler to either assemble or skip a block of statements 
depending an the value of an expression at assembly time; this 
is called conditional assembly . With this facility, totally 
different object programs can be generated, depending on the values 
of a few parameters. 

Macros : A macro is a block of text defined somewhere in the 
program and given a name. Later references to this name cause 
the reference to be replaced by the block of text. Thus, the 
macro facility can be thought of as an abbreviation or shorthand 
notation for one or more assembly language statements. The macro 
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facility is more powerful than this, however, since a macro may 
have formal arguments which are replaced "by actual arguments when 
the macro is called. 

One -pass assembly : Instead of processing a source program twice 
as was described above (section 1.1), NARP accomplishes the same 
task in one scan over the source program. The method used is 
rather complex and is described elsewhere, ( implementation of 
NARP, Doc. M-l6) 
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2.0 Basic constituents of NARP 



2.1 Character set 



All the characters listed in Appendix B have meaning in 
NARP except for '?' and f V*. The following classification of 
the character set is useful: 

letter: A-Z 

octal digit : 0-7 

digit: 0-9 

alphanumeric character: letter or digit or colon 

terminator: , ; blank CR (denotes carriage return) 

operator: !#$&* + -/<=><£? t 

delimiter: "$♦()[].«_ 

The multiple-blank character (l35o) may appear anywhere that a 
blank is allowed. All characters with values greater than 77~ are 
ignored except for multiple -blank character (l35o) and carriage 
return (l55g)- 

2.2 Statements and format 

The logical unit of input to NARP is the statement,a sequence 
of characters terminated by a semi-colon or a carriage return. 
There are five kinds of statements: 

1. empty: A statement may consist of no characters at all, or only 

of blank characters. 

2. comment: If the very first character of a statement is an 

asterisk, then the entire statement is treated as a 
comment containing information for a human reader. 
Such statements generate no output. 

The format for the next three kinds of statements is split into 

four fields: 

label field : This field is used primarily for symbol definition; 
it begins with the first character of the statement and 
ends on the first non- alphanumeric character (usually a 
blank). 
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opcode field: This field contains a directive name, a macro 
name, or an instruction (i.e., any opcode other than a 
directive or macro). The field begins with the first 
non-blank character after the label field and terminates 
on the first non-alphanumeric character; legal terminators 
for this field are blank, asterisk, semi-colon, and 
carriage return. 

operand field : The operand for an instruction, macro, or 

directive appears in this field, it begins with the first 
non-blank character following the opcode field and terminates 
on the first blank, semi-colon, or carriage return. Mote 
that a statement may terminate before the operand field. 

comment field : This field contains no information for NARP but 
may be used to help clarify a program for a human reader. 
The field starts with the first non-blank character after 
the operand field (or after the opcode field if the opcode 
takes no operand) and ends on a semi-colon or carriage return. 

Now we continue describing the kinds of statements: 
3. instruction: If the opcode field of a statement does not contain 
a directive name or a macro name, then the statement is 
an instruction. An instruction usually has an expression 
as an operand and generates a single machine word of 
program. See section 3 for a detailed description of 
instructions. 
k. directive: If a directive name appears in the opcode field, then 
it is a directive statement. The action of each directive 
is unique and thus each one is described separately (in 
section h) . 
5. macro: A macro name in the opcode field of a statement indicates 
that the body of text associated with the macro name should 
be processed (see section 5)- 

Example of various kinds of statements: 

* FOLLOWING ARE TV/0 DIRECTIVES (MACRO, ENDM) WHICH DEFINE 

♦ THE MACRO SKAP 

SKAP MACRO; SKA =J+B7; ENDM 
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* NOW SKAP IS CALLED: 

LDA ALPHA 

SKAP; BRU BAD IF NEGATIVE THEN ERROR 
OKAY ADD BETA NOW A=ALPHA+BETA; BRU GOOD 



In subsequent sections the details of instructions, directives, 
and macros will be explained, but first some basic constituents 
and concepts common to all of these statements will be discussed. 

2.3 Symbols, numbers, and string constants 

Any string of alphanumeric characters not forming a number 
is a symbol, but only the first six characters distinguish the 
symbol (thus QI23U5 is the same symbol as QI23U56). Note that 
a symbol may begin with a digit, and that a colon is treated as 
a letter (as a matter of good programming practice, colons should 
be used rarely in symbols, although they are often useful in 
macros and other obscure places to avoid conflicts with other 
names). In the next section the definition and the rf actors 
of symbols are discussed. 

A number is any one of the following: 

a) A string of digits 

b) A string of digits followed by the letter 'D* 

c) A string of octal digits followed by the letter 'B' 

d) A string of octal digits followed by the letter f B' 
followed by a single digit. 

A D-suffix indicates the number is decimal, whereas a B-suffix 
indicates an octal number. If there is no suffix, then the 
current radix is used to interpret the number (the current 
radix is initially 10 but it may be changed by the OCT and DEC 
directives). If the digit 8 or 9 is encountered in an octal 

number, then an error message is typed. If the value of a 

23 
number exceeds 2 -1 overflow results; HARP does not check for 

this condition, and in general it should be avoided. A B-suffix 

followed by a digit indicates an octal scaling; thus, 7^B3=7^000B. 

Examples : 

symbols: START 1M CALCULATE 14D2 ltaO 

numbers: Ik l8D 773B 777B? 13B9 
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A string constant is one of the following: 

a) A string of 1 to 3 characters enclosed in double 
quotes ("). 

b) A string of 1 to k characters enclosed in single 
quotes ( ' ) . 

In the first case the characters are considered to be 8 bits 
each (thus only 3 can be stored in one machine word), while in 
the second case they are considered to be 6 bits each. In both 
cases, strings of less than the maximum length (3 or k, as the 
case may be) are right- justified. Thus 

IAt _ I At - *»" - » A" 

where ^_ denotes a blank. If a string constant is too long, then 
an error message is typed and only the first 3 (or k) characters 
are taken. Normally string constants are not very useful in 
address computation, but are most often used as literals: 



LDA 


WORD 


SKE 


^GO' 


BRU 


STOP 



Both numbers and string constants are absolute, i.e., their 
rf actor is zero. 

2.U Symbol definitions 

Since NARP is a one -pass assembler, the statement that a 

symbol or expression is "defined" usually means that it is defined 

at that instant and not somewhere later in the program. Thus, 

assuming ALHIA is defined nowhere else, the following 

BETA EQU ALPHA 
ALPHA BSS 3 

is an error because the EQU directive demands a defined operand 
and ALFHA is not defined until the next statement. This convention 
is not strictly adhered to, however, since sometimes the state- 
ment "XYZ is not defined" will mean that XYZ is defined nowhere 
in the program. 

A symbol is defined in one of two ways : by appearing as a 
label or by being assigned a value with an EQU directive (or 
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equivalent ly, by being assigned a value by NARG, NCHR, EXT 
(see below), or by being used in the increment list of a RPT 
or CRPT statement). This latter sort of symbol is called 
e quated . 

Labels: If a symbol appears in the label field of an 

instruction (or in the label field of some directives) 
then it is defined with the current value of the location 
counter (rfactor=l). If the symbol is already defined, 
either as a label or as an equated symbol, the error 
message '(Symbol) REDEFINED ' is typed and the old 
definition is completely replaced by the new one. 

Equated symbols: These symbols are usually defined by EQU, 

getting the value of the expression in the operand field 
of the EQU directive. This expression must be defined 
and have an rf actor in the range [ -15 , 15 ] • If the symbol 
has been previously defined as a label, then the error 
message '(Symbol) REDEFINED' is typed and the old definition 
is completely replaced by the new one; if the symbol has 
already been defined as an equated symbol, then no error 
message is given, and the old value and rfactor are 
replaced by the new ones. Thus, an equated symbol can be 
defined over and over again, getting a new value each time. 

A defined symbol is always local, and may also be external. 
If a symbol in package A is to be referred to from package B, 
it must be declared external in package A. This is done in 
one of the following ways: 

Declared external by $: If a label or equated symbol is 

preceded by a $ when it is defined, then it is declared external. 

$LABEL1 LDA ALPHA 

IABEL2 STA BETA LABEL2 IS LOCAL ONLY 

$GAMMA EQU DELTA 
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Declared external by the EXT directive: There are two cases: 

i) EXT has no operand: The symbol in the label field is declared 

external; it may have already been declared external or may 

even have a $ preceding it. 

ii) EXT has an operand: This case is treated exactly like the 

case: $label EQU operand. 

Certain symbols are pre-defined in NARP, i.e., they already 

have values when an assembly begins and need not be defined by 

the programmer: 

:ZERO: This is a relocatable zero (i.e., value = 0, r factor = l) 

:I£: This symbol is initially zero (rfactor=l) and remains 

so until the END directive is encountered and all literals 

are output, at which time it gets the value of the location 

counter. See the description of FREEZE for a discussion 

of the use of this symbol. 

* Syntactically this is not a symbol, but semantically 

it acts like one. At any given moment, * has the value 

of the location counter (rfactor=l), and can thus be used 

to avoid creating a lot of local labels. 

Thus CIA; LDX LENGTH 

LOOP STA TABLE, 2; BRX LOOP 

can be written as 

CLA; LDX LENGTH; STA TABLE, 2; BRX *-l 

If a given symbol is referred to in a program, but is not 
defined when the END directive is encountered then it is assumed 
that this symbol is defined as external in some other package . 
Whether this is the case cannot be determined until the various 
packages have been loaded by DDT. Such symbols are called 
"undefined symbols" or "external symbol references." It is 
possible to perform arithmetic upon them (e.g., LDA UNDEF+l); 
an expression in post-fix Polish form will be transmitted to DDT. 
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2.5 Expressions and literals 

Loosely speaking, an expression is a sequence of constants 
and symbols connected by operators. Examples: 
100-2*ABC/ [ALPHA+BETA] 
GAMMA 
E>=Q 

Following is the formal description (in Backus normal form) 
of a NARP expression: 

<primary>: :»<number>|<string constants |<symbol>|*|[<expr>] 

<expr>: :«<primary>|<unary operator> <expr> |<expr> <binary operator> <expr: 

<expression>: :=<expr>|<literal operator> <expr> 

<binary operator>: :=t |*|/|+|- |<|<«| = |#|>=j> j&| ! \% 
<unary operator>: :=+|-|# 
<literal operator> : : = * 

Notice that the literal operator is rather special, only 
being allowed to appear once in a given expression, and only 
as the first character of the expression. Literals are 
discussed in greater detail below. 

The value of an expression is obtained by applying the 
operators to the values of the constants and symbols, evaluating 
from left to right except when this order is interrupted by the 
precedence of the operators or by square brackets* ([,]); the 
result is interpreted as a 2U-bit signed integer. The following 
table describes the various operators and lists their precedences 
(the higher the precedence, the tighter the operator binds its 
operands ) : 



* 
not parentheses'. 
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Operator 



Precedence 



Comment 



t 


6 


exponentiation; exponent must be > 


* 


5 


multiplication 




/ 


5 


integer division 




+ (u) 


4 


unary plus 




- (u) 


1+ 


negation (arithmetic) 




+ 


1+ 


addition 




- 


1* 


subtraction 




< 


3 


less than 




<« 


3 


less than or equal to 


result of operati 


= 


3 


equal to 




h if relation is 


# 


3 


not equal to 




otherwise 1 


>= 


3 


greater than or equal 


to 




> 


3 


greater than 


n 




#(u) 


2 


logical not 






& 


1 


logical and 




logical operation 


t 





logical or 


\ applied to all 


i 





logical exclusive or 


f 


24 bits 



IS 

false, 



The r factor of an expression is computed at the same time 
the value is computed. There are constraints, however, on the 
rf actors of the operands of certain operators, as shown in the 
table below: (Note: Rl is a symbol with an rfactor of 1, R2 
is a symbol with an rfactor of 2). 





relocation factor(s) 


relocation factor 




operator 


of operand(s) 


of result 


examples 


t 






■2t^l6, 
Rltl( error) 


& ! 


all operands absolute 


absolute 


7&3=3, 
6«R1( error) 


/ 






V2=2, 
Rl/l (error) 


* 


at least one rfactor 


found by multi- 


3*R2 has 




must be absolute, the 


plying the value 


rfactor of 6, 




other is arbitrary 


of the absolute 
operand times the 
rfactor of the 
other operand 


Rl*Rl( error) 


< <* = 


arbitrary relocation 




R1=*R1 is true 


#>*> 


factors, but must be 
equal 


absolute 


R2>Rl(error) 


+ 




found by applying 


R1+R2 has 


(unary and 
binary) 


arbitrary rf actors 

..... 


operator to the 
relocation factors 

of the operands 


relocation 
factor of 3 
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The final rf actor of an expression must be in the range 

[-8191, 8191]. 

If an expression contains an undefined symbol or if it is a 
literal, then the entire expression is undefined. 

Although a literal is a special kind of expression, it is 
often convenient to think of it as a quite separate entity. The 
use of literals is discussed below. 
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Programmers frequently write such things as 

LDA FIVE 

where FIVE is the name of a cell containing the constant 5. The 
programmer must remember to include the datum FIVE in his program 
somewhere. This can be avoided by the use of a literal. 

LDA =5 

will automatically produce a location containing the correct 

constant in the program. Such a construct is called a literal. 

When a literal is encountered, the assembler first evaluates the 

expression and looks up its value in a table of literals constructed 

for each subprogram. If it is not found in the table, the value 

is placed there. In any case the literal itself is replaced by 

the location of its value in the literal table. At the end of 

assembly the literal table is placed after the sub-program. 

The following are examples of literals: 

=10 =UB6 =ABC*20-DEF/l2 ='HELP' 

=2>AB (This is a conditional literal. Its value will 
be 1 or depending on whether 2>AB at assembly 
time. ) 

Some programmers tend to forget that the literal table 

follows the subprogram. This could be harmful if the program 

ended with the declaration of a large array using the statement 

ARRAY BSS 1 

It is not strictly correct to do this, but some programmers 

attempt it anyway on the theory that all they want to do is to 

name the first cell of the array. The above statement will do 

that, of course, but only one cell will be reserved for the 

array. If any literals were used in the subprogram, they would 

be placed in the following cells which now fall into the array. 

This is, of course, an error. Other than this exception, the 

programmers need not concern himself with the locations of the 

literals . 
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3.0 Instructions 

There are three different syntactical forms of instruction 
statements, depending on the class of the instruction in the 
opcode field: (in the following, syntactical elements enclosed 
in square brackets are optional; they may or may not be present.) 

class 0: [[$]label] opcodef*] [operandi, tag] [comment]] 

class 1: [[$]label] opcode[*] [comment] 

class 2: [[$] label] opcode [*] operand[ ,tag] [comment] 

Each of the syntactical elements is discussed below: 

$ : A label preceded by a dollar sign is declared external 
(see section 2. if). 

label : The label is defined with the current value of the 
location counter (rfactor=l) . 

opcode : The opcode must be either an instruction which is 

already defined or a number. If it is a number, then 
the value (mod 2^) of the number is placed in b0-b8 
(bit through bit 8) of the instruction, and it is 
treated as a class opcode (i.e., operand optional). 

* : If an asterisk follows immediately after the opcode 
then b9 (the indirect bit) of the instruction is set. 

operand: The operand is an expression which may or may not be 

defined and which has any rf actor. The expression may 

be preceded by '/' or l< -' (° r both in any order); 

these characters cause the following bits to be set: 

/ bl (index bit) 

«- b9 (indirect bit) 

Thus: 

LDA /VECTOR is the same as LDA VECTOR, 2 
STA f-POINTER is the same as STA* POINTER 
LDA *-/CCMHX is the same as LDA* C0MPLX,2 
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tag : The tag is an expression which must be defined and 
absolute. Its value (mod 2 J ) is placed in b0-b2 of 
the instruction. 

comment: The comment does not affect the instruction generated; 
it may be listed. 

In addition to its class, a given opcode is designated as 
being either a shift instruction or a non-shift instruction. 
This has nothing to do with whether the action of the instruction 
involves shifting, but is simply a way of distinguishing between 

two kinds of instructions. For non-shift instructions, operands 

Ik 
are computed mod 2 , while for shift instructions there are two 

possibilities: 

a) If the indirect bit is set by '*' or '*-', then the value 
of the opcode is trimmed so that bl0-b23 are zero, and 
then the instruction is treated as if it were a non- 
shift instruction. 

b) If the indirect bit is not set as above, then the 

9 
operand is computed mod 2'; it must be defined and 

absolute. 



4-1 



4.0 Directives 



There are many directives in NARP; although some of them are 
similar, each in general has its own syntax. Following is a 
concise summary: 



Class 



Directive Use or Function 



Mnemonic for instructions: COPY 



Mnemonic for RCH 



Section 
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Data generation 



: DATA. 
ASC 

TEXT 



Generate data 4.5 

Generate text 

(3 characterrper word) 4.1 

Generate text (4 

characters per word) 4.23 



Value declaration 



EQU 

EXT 

NARG 
NCHR 
OPD 
POPD 



Equate a symbol to 

a value 4.9 
Define a symbol as 

external 4.10 

Number of arguments 5»5 

Number of characters 5.5 

Define an opcode 4.17 
Define a programmed 

operator 4.19 



Assembler control 



: BES 
BSS 
END 
DEC 

OCT 

FRGT 

FRGTOP 



IDENT 



Block ending symbol 4.2 

Block starting symbol 4 . 3 

End of assembly 4.8 

Interpret integers 

as decimal 4.6 

Interpret integers 

as octal 4.16 

Do not output a 

specific symbol 4.12 

Suppress output 

of opcode 4.125 

Identification of 

a package 4.13 
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Class 



Directive Use or Function Section 

DELSYM Do not output any 

symbols 4.7 

RELORG Assemble relative 

with absolute origin 4.20 

RETREL Return to relocatable 

assembly 4.22 

FREEZE Preserve symbols, 

opcodes, and macros 4.11 



Output and listing 
control 



LIST 

NOLIST 

PAGE 

REM 



Set listing controls 4.14 

Reset listing controls 4.15 

Begin a new page on 

the listing 4.18 

Type out remark 4.21 



Conditional assembly 
and macros 



IF 


Begin if body 


ELSF 


Alternative if body 


ELSE 


Alternative if body 


ENDF 


End if body 


RPT 


Begin repeat body 


CRPT 


Begin conditional 




repeat body 


ENDR 


End repeat body 


MACRO 


Begin macro body 


IMACRO 


Alternative to MACRO 


ENDM 


End macro body 



5-1 
5-1 
5.1 
5-1 
5.2 

5.2 

5-2 
5.4 
5-4 
5.4 



In the remainder of this section, all directives listed 
above except for those associated with conditional assembly and 
macros are described. 
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k.l ASC Generate text (3 characters per word ) 

[[$] label] ASC string [comment] 

This directive creates a string of 8-bit characters stored 
3 to a word. The string starts in the leftmost character of a 
word and takes up as many words as needed; if the last word is 
not filled up completely with characters from the string, then 
the right end of the word is filled out with blanks. If a label 
appears, its value is the address of the first word of the 
string. The syntactical element "string" is usually any 
sequence of characters (not containing a single quote) surrounded 
by single quotes. However, the first character encountered 
after 'ASC is used as the string delimiter (of course, blanks 
and semi-colons cannot be used as string delimiters). 



Examples: 



ASC 'NO SINGLE QUOTES, HERE IS A SEMI-COLON:;' 
$ALFHA ASC $HERE IS A SINGLE QUOTE: '$ 



k.2 BES Block ending symbol 

[[$] label] BES expression [comment] 

The location counter is incremented by the value of the 
expression in the operand field and then the label (if present) 
is given the new value of the location counter. Thus, in 
effect, a block of words is reserved and the label addresses 
the first word after the block. The expression must be defined 
and absolute. This directive is most often used in conjunction 
with the BRX instruction, as in the following loop for adding 
together the elements of an array: 

LDX =*-LENGTH; CLA; ADD ARRAY, 2 
BRX *-l; STA RESULT; HLT 
ARRAY BES LENGTH 
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^•3 BSS Block starting symbol 

[[$]label] BSS expression [comment] 

This directive does exactly the same thing as BBS except that 
the label (if present) is defined before the location counter 
is changed. Thus, the label addresses the first word of the 
reserved block. It should be noted that the expression for both 
BES and BSS may have a negative value, in which case the location 
counter is decremented. 
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k.k COPY Mnemonic for RCH 



[[$]label] COPY s ,s ,s , ... [comment] 

(where s. are s; 
COPY directive) 



(where s. are symbols from a special set associated with the 



The COPY directive produces an RCH instruction. It takes 
in its operand field a series of special symbols, each standing 
for a bit in the address field of the instruction. The bits 
selected by a given choice of symbols are merged together to 
form the address. For example, instead of using the instruction 
CAB (CkGOOOCh), one could write COPY AB. The special symbol 
AB has the value 0000000*+. 

The advantage of the directive is that unusual combinations 
of bits in the address field — those for which there exist 
normally no operation codes — may be created quite naturally. 
The special symbols are mnemonics for the functions of the 
various bits. Moreover, these symbols have this special meaning 
only when used with this directive; there is no restriction on 
their use either as symbols or opcodes elsewhere in a program. 
The symbols are: 

Symbol Bit Function 



A 


23 


Clear A 


B 


22 


Clear B 


AB 


21 


Copy (A) -> B 


BA 


20 


Copy (B) -*A 


BX 


19 


Copy (B) -♦X 


XB 


18 


Copy (X) ->B 


E 


17 


Bits 15-23 (exponent part) only 


XA 


16 


Copy (X) ->A 


AX 


15 


Copy (A) ->X 


N 


Ik 


Copy -(A) -> A (negate A) 


X 


1 


Clear X 



To exchange the contents of the B and X registers, negate A, 
and only for bits 15-23 of all registers, one would write 
COPY BX,XB,N,E 
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If. 5 DATA Generate data 

[ [ $] label] DATA e-^ , e 2 ,e- , . . . [ comment] 

The DATA directive is used to produce data in programs. 
Each expression in the operand field is evaluated and the 2*J-bit 
values assigned to increasing memory locations. One or more 
expressions may be present. The label is assigned to the 
location of the first expression. The effect of this directive 
is to create a list of data, the first word of which may be 
labeled. 

Since the expressions are not restricted in any way, any 
type of data can be created with this directive. For example: 

DATA 100,-217B,START,AB*2/EEF, 'HUTS' ,5 
creates six words. 
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h.6 DEC Interpret integers as decimal 

DEC [comment] 

The radix for integers is set to ten so that all following 
integers (except those with a B- suffix) are interpreted as 
decimal, ^hen an assembly begins the radix is initialized to 
ten, so IEC need never "be used unless the OCT directive is used. 
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k.7 DELSYM Do not output any symbols 

DELSYM [comment] 

If DELSYM appears anywhere in a program being assembled, 
the symbol table and opcode definitions will not be output 
by NARP when the END directive is encountered. The main purpose 
of this directive is to shorten the object code generated by 
the assembler, especially when the symbols are not going to 
be needed later by DDT. 
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k.8 END End of assembly 

END [comment] 

When this directive is encountered the assembly terminates. 
If the LIST directive has been used then various information may 
be listed, for example undefined symbols. 



U.9 EQU Equate a symbol to a value 

[$]symbol EQU expression [comment] 

The symbol is defined with the value of the expression; if 
the symbol is already defined, its value and rf actor are changed. 
The expression must be defined and must have an rf actor in the 
range [-15,15]. If the symbol has been declared external before 
or if it has been forgotten (using FRGT) then EQU preserves this 
information . Thus 



$ALPHA. EQU k 
ALPHA EQU 3 



will cause ALPHA to be declared external but with a value of 
three at the end of the assembly (provided ALPHA is not changed 
again before the END directive). See section 2.k for more 
discussion of EQU. 
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1+.10 EXT Define a symbol as external 

[$] symbol EXT [expression [comment]] 

This directive is used to declare symbols as external. See 
section 2.U for a discussion of the various cases. 
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l+.ll FREEZE Preserve symbols, opcodes, and macros 

FREEZE [ comment ] 

Sometimes subprograms share definitions of symbols, opcodes, 
and macros. It is possible to cause the assembler to take note 
of the current contents of its symbol and opcode tables and the 
currently defined macros and include them in future assemblies, 
eliminating the need for including copies of this information 
in every subprogram's source language. 

When the FREEZE directive is used, the current table 
boundaries for symbols and opcodes and the storage area for macros 
is noted and saved away for later use. These tables may then 
continue to expand during the current assembly. (A separate 
subprogram may be used to make these definitions; it will then 
end with FREEZE; END.) The next assembly may then be started 
with the table boundaries returned to what they were when FREEZE 
was last executed. This is done by entering the assembler 
at its "continue" entry point, i.e., by typing 

£ CONTINUE NARP. 
Note that the assembler cannot be released (i.e., another 
subsystem like QED or DDT cannot be used) without losing the 
frozen information. 

In conjunction with the FREEZE directive, the predefined 

symbol :LC: is useful, especially when writing large 

re-entrant programs. Following is a three -package program 

using FREEZE and :LC:. 

PI IDENT 

<definitions of macros, opcodes, and global equated 

symbols> 
<definition of working storage (i.e., read-write 

memory )> 
FREEZE 
END 

P2 IDENT 

BSS :LC:-:ZERO: 
<read-only code> 
END 



1+-1U 



PI 3DEWT 

BSS :LC:-:ZERO: 
<read-only code> 
END 

The FREEZE directive at the end of PI preserves all the 
definitions in this package so they can be referenced in packages 
P2 amd P3. By including the definitions of all the working storage 
cells in the preserved definitions, these symbols need not be 
declared as external. Also, it makes "external" arithmetic on these 
symbols possible in P2 and P3t and it reduces the number of 
undefined symbols printed at the end of an assembly. Packages 
P2 and ?3 start with the rather -peculiar looking BSS in order 
to set the location counter so that references between the 
packages will be correct. This is the main purDOse of :I£:, 
it saves the final value of the location counter from the 
previous package for use by the current package. In order for 
this scheme to work, a.1.1 three packages must be loaded at the 
same location, usually for large re-entrant programs. 

Assume ALPHA is a symbol defined in PI. Unless some 
special action is taken, AUHA will be output to DOT three times, 
once at the end of PI, once at the end of P2, and once at the end 
of P3. To avoid this, all symbol and opcode definitions are 
marked after they have been output once so that they won't be 
output again. 
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If . 12 FRGT Do not output a specific symbol 

FRGT s ,s 2 , ... [comment] 

The symbols s. (which must have been previously defined) 
are not output to DDT. FRGT is especially useful in situations 
where symbols have been used in macro expansions or conditional 
assemblies, and have meaning only at assembly time. When DDT 
is later used, memory locations are sometimes printed out in 
terms of these meaningless symbols. It is desirable to be 
able to keep these symbols from being delivered to DDT, hence 
the FRGT directive. 
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k.125 FRGTOP Forget selected opcodes 
FRGTOP s , s 2 , . . . [ comment] 

The s. must be opcodes. The specified opcodes are marked 
as forgotten and will not be output to DDT. Since DDT knows 
in advance about the standard instruction set (e.g., LDA, BRS, 
CIO), FRGTOP or such opcodes has no effect. It follows that 
the chief use of FRGTOP will be to suppress output of opcodes 
generated by OPD and POPD. 

FRGTOP does not take a label. 
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k. 13 IDENT Identification of a -package 

symbol IDENT [comment] 

The symbol in the label field is delivered to DDT as a 
special identification record. DOT uses the IDENT name in con- 
junction with its treatment of local symbols: in the event of 
a name conflict "between local symbols in two different subprograms, 
DOT resolves the ambiguity by allowing the user to concatenate 
the preceding IDENT name with the symbol in question. Also, 
during an assembly the first six characters of the symbol followed 
by the word 'IDENT* are typed on the teletype to show the user 
what package is being assembled. The progress of an assembly- 
can be followed by placing IDENT* s at various points in the 
package . 
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4.135 LIBEXT Specify library symbol 
Symbol LIBEXT [comment] 

This directive causes "symbol" to be output to the binary 
file, marked as a special "library- symbol." The resulting 
binary file must then be mauled by a library-making program 
before it will be intelligible to the loader in DDT. 

The library-maker takes a binary file and moves all of the 
library- symbols to the beginning of the program, and puts the 
result on a file as a "library-program." When a "library- file" 
(which contains one or more library-programs) is loaded into 
DDT, the loader scans the list of library symbols before each 
library- program. If any of them is currently undefined (i.e., 
referenced but not defined in previously loaded programs), the 
associated library-program is loaded normally; otherwise, it 
is not loaded. 

For example, one could write a sine and cosine library program: 
SIN LIBEXT 

*SINE ROUTINE: ANGLE IN RADIANS 
$SIN ZRO SINX 

(sine routine code) 

COS LIBEXT 

*COSINE ROUTINE: ANGLE IN RADIANS 
$COS ZRO COSX 

(cosine routine code) 

END 

Assemble it with NARP and use the library-maker to put it on 
a library- file as a library- program. Then, if either "SIN" 
or "COS" is undefined when the library-file is loaded, both 
the sine and cosine subroutines will be loaded, and the symbols 
"SIN" and "COS" defined as the entry points of the routines 
(respectively). (If one desired to have them load independently, 
each subroutine could be made into a separate library-program.) 
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(Note: The library-program is loaded normally once the decision 
to load it has been made; thus, undefined library- symbols will 
only be defined and linked in previously-loaded programs if they 
are defined and made external in the library-program in the 
usual fashion (as in the example).) 
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k.lk LIST Set listing controls 



k.15 NOLIST Reset listing controls 

[comment]] 



r LIST ^ 



NOLIST i r 



C^, ... 



There are various booleans which control the format in 
•which statements are listed (certain fields and/ or certain 
kinds of statements may be suppressed, or listed selectively) . 
The user is allowed to set (or reset) these booleans via the 
LIST (or NOLIST) command. Each of the S. may be one of the 
following special symbols: 



s. Set (or 
1 


reset) 


What is (or is not) listed 


LCT 




the current value of the location 
counter, in octal 


SLCT 




the symbolic address of the current 
value of the location counter 


VAL 




the value of the statement, if it is 
one of the directives: EQU, NCHR, 
NARG, IF, ELSF. (in octal) 


SRC 




the symbolic source code 


COM 




the comment field of a statement, a 
comment statement 


CALL 




macro and RPT calls 


DEF 




MACRO and RPT definitions 


EXP 




macro and RPT expansions 


SKIF 




the skipped parts of an IF statement 


EXT 




external symbol references (at the 
end of the assembly 
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In addition, s. may be "ALL", which will cause all of the 
booleans in the table to be set (or reset). 

If a LIST (or NOLIST) directive is encountered for which 
no arguments (s.) have been specified, NARP will begin (or 
cease) listing statements on the LISTING FILE (the teletype, 
in case no other listing file is specified when the assembly 
is begun) according to the current settings of the listing 
booleans. Including "GO" among the arguments for a LIST 
(or NOLIST) will have the same effect. 

When NARP is called, the listing booleans are initialized 
as follows : 

Set: LCT, VAL, SRC, COM, CALL, DEF, EXP, EXT 
RESET: SLCT, SKIF 

and NARP is in its "no list" state, i.e., listing will not 

be started unless (and until) the program initiates it with a 

LIST directive. 

Examples of the LIST directive: 

NOLIST ALL Resets all format booleans 

LIST SRC, GO Sets SRC boolean and starts listing. 

(only the source code will be listed) 

Examples of listing format: 

LCT SLCT VAL SRC COM ^ ' 

l *— i ^ * *r--^^—» c r— * — "f ==:: ^ ^ "> 



00117 (A) 3 A EQU 6/2 (SET A) 
00117 (HERE) HERE LDA A*B,2 
00120 (HERE+1) CLB 
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U»l6 OCT Interpret integers as octal 

OCT [comment] 

The radix for integers is set to eight so that all following 
integers (except those with a D- suffix) are interpreted as octal. 
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k.lf OFD Define an opcode 

symbol OFD value [, class [, shift kludge]] 

The symbol in the label field is defined as an opcode with 
a value equal to the first expression in the operand field. All 
expressions in the operand field must be defined and absolute; if 
an optional expression does not appear then the value is assumed. 

value : computed mod 2 (see important note below; 

class : must have a value of 0,1, or 2: 

- the opcode may or may not have 

an operand 

1 - the opcode does not take an 

operand 

2 - the opcode requires an operand 

shift kludge: must have a value of or 1: 

- non- shift instruction 

(see section 3) 

1 - shift instruction (see section 3) 

Note: Although an opcode that takes operands can be defined with 
bits blO-b23 set, the user must be careful of what he is doing. 
In particular, if such an opcode appears in an instruction which 
contains a literal or an undefined value then bits bl0-b23 of the 
opcode are set to 7.ero. 

If the symbol in the label field is already defined as an 
opcode then the old definition is lost. 
Examples : 

055B5,2 

0^600001B,1 

0662B^,2,1 

020B5 



ADD 


OPD 


CLA 


OFD 


ROY 


OPD 


NOP 


OPD 
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k . 19 POPD Define a programmed operator 

symbol POPD valuef, class [, shift kludge]] 

This directive does exactly what OPD does with one addition: 
The instruction BRU* is placed in the memory location whose 
address is in b2-b8 of the value given to the symbol (this 
address must be in the range [100B, 177B]). Thus 



THE CALL 'MIN ALPHA* WILL 
CAUSE THE MINIMUM OF 
A -REG AND ALPHA TO BE 
LEFT IN A-REG. 

will cause BRU LMIN to be loaded in word 100B. 



MIN 


POPD 


100B5,2 


IMIN 


SKG* 







BRR 







LDA* 







BRR 
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^.20 RELORG Assemble relative with absolute origin 

RELORG expression [comment] 

On occasion it is desirable to assemble in the midst of 
otherwise normal program a batch of code which, although loaded 
in core in one position, is destined to run from another position 
im memory, (it will first be moved there in a block.) This is 
particularly useful when preparing program overlays. The 
expression in the operand field (which must be absolute and 
defined) denotes an origin in memory. The following occurs when 
the directive is encountered: 

a.) The current yalue of the location counter is saved, and 

in its place is put the absolute origin (i.e., the 

value of the expression). This fact is not revealed 

to DET, however, so during loading the next instruction 

assembled will be placed in the next memory cell available 

as if nothing had happened, 
b.) The mode of assembly is switched to absolute, i.e., all 

symbols defined in terms of the location counter will 

be absolute. 
It is possible to restore normal relocatable assembly (see section 
if. 22). 

As an example of the use of RELORG, consider a program 
beginning with REI/)RG 300B. The assembler's output represents 
an absolute urogram whose origin is 00300©, but which can be 
loaded anywhere using DOT in the usual fashion. Of course, 
before executing the program it will be necessary to move it to 
location OOSOOq. 

As another example, consider the following use of REIORG and 
RETREL: 

<normal relocatable program> 

RELORG lOCB 

<ab solute program with origin at 10QB> 

RELORG 200B 

<absolute program with origin at 200B> 
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KETREL 

<normal relocatable program> 

RELORG 300B 

<ab solute program with origin at ^OGB> 

END 
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^.21 REM Type out remark 

REM text 

This directive causes the text in its operand and comment 
fields to be typed out either on the teletype or whatever file 
has been designated as the text file (see section 6.2). This 
typeout occurs regardless of what listing controls are set. The 
directive may be used for a variety of purposes : It may inform 
the user of the progress of assembly; it may give him instructions 
on what to do next (this might be especially nice for complicated 
assemblies); it might announce the last date the source language 
was updated; or it might be used within complex macros to 
show which argument substrings have been created during 
expansion of a highly nested macro (for debugging purposes). 
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4.22 RETREL Return to relocatable assembly 

RETREL [comment] 

This directive is used when it is desired to return to 
relocatable assembly alter having done a RELORG. It is not 
necessary to use RETREL unless one desires more relocatable 
program. An example of the use of RETREL is shown in section 
4.20. The effects of RETREL are 

a . ) to restore the location counter to the value it would 

have had if the RELORG (s) had never appeared, and 
b.) to return the assembly to relocatable mode so that 
labels are no longer absolute. 



U.23 TEXT Generate text (k character per word ) 

[[$] label] TEXT string [comment] 

This directive is exactly the same as ASC (see section k.l) 
except that characters are taken as six hits each and are stored 
four to a word. 
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5-0 Conditional assemblies and macros 



5.1 IF, ELSF, ELSE, and ENDF 



If statements 



It is frequently desirable to permit the assembler either to 
assemble or to skip blocks of statements, depending on the value of 
an expression at assembly time. This is primarily what is meant 
by conditional assembly . In NARP, conditional assembly is done 
by using either an if statement or a repeat statement . 

The format of an if statement is 



IF expression 

< if body > 

ENDF [comment] 



[comment] 



The if body is any block of NARP statements, in particular, it may 
contain directives of the form 



and 



ELSF 



ELSE 



expression 
[ comment ] 



[ comment 3 



If the operand of IF is true, then the block of code up to the 
matching ENDF (or ELSF or ELSE) is processed; otherwise, it is 
skipped. The values for true and false are: 



true 


: value of 


expression 


false 


: value of 


expression 


s: 

IF 
LDA 
STA 
ENDF 


1>0 

ALPHA 1 
BETA J 


processed 


IF 
LDA 
STA 
ENDF 




GAMMA -1 

DELTA J 


skipped 
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Often there are more than two alternatives, so the ELSF 
directive is used in the if body. When ELSF is encountered while 
skipping a block of statements, its operand is evaluated (just 
as for IF) to decide whether to process the block following the 
ELSF. 



• 

IF 


> 1 




LDA 


ALPHA 


skipped 


ELSF 


1 > 




LDA 


BETA 


processed 


ENDF 






IF 


> 1 




LDA 


ALPHA 


skipped 


ELSF 


> 1 




LDA 


BETA 


skipped 


ENDF 






IF 


1 > 




LDA 


ALPHA 


processed 


ELSF 


1 > 




LDA 


BETA 


skipped 


ENDF 






IF 


0> 1 




LDA 


ALPHA 


skipped 


ELSF 


1> 




LDA 


BETA 


processed 


ELSF 


1> 




LDA 


GAMMA 


skipped 


ENDF 







From the last two examples above it should be clear that either 
no blocks are processed or precisely one is; thus, as soon as one 
block is processed, all following blocks are skipped regardless 
of whether the ELSF expressions are true. 
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An ELSE directive is equivalent to an ELSF directive with a 
true expression. 
Example : 



IF 


> 1 




LDA 


ALPHA 


skipped 


ELSE 






LDA 


BETA 


processed 


ENDF 







As a more general example, consider the following: 

IF el 

< body 1 > 
ELSF e2 

< body 2 > 
ELSF e3 

< body 3 > 
ELSE 

< body k > 
ENDF 

There are four possibilities: 



a) el > 

b) el < 0, e2 > 

c) el < 0, e2 < 0, 

e3> 

d) el < 0, e2 < 0, 

e3 < 



process body 1, skip the other three 
process body 2, skip the other three 

process body 3, skip the other three 

process body k 3 skip the other three 



The bodies between the IF, ELSF, ELSE, and ENDF directives 
may contain arbitrary NARP statements, in particular they may 
contain other if statements. This nesting of if statements may 
go to any level. 

When evaluating the expression in the operand field of IF or 
ELSF, all undefined symbols are treated as if they were defined with 
value -1. These expressions must be absolute. 
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5.2 RPT, CRPT, and ENDR Repeat statements 

A repeat statement is a means of processing the same text many 
times. The format is 

[ [ $ 3 label] RPT expressionf , increment list ] [ comment ] 
< repeat body > 
ENDR [comment] 

The value of the RPT operand (which must be defined and absolute) 

determines how many times the repeat body will be processed) while 

the increment list (described below) is a mechanism to allow the 

values of various symbols to be changed each time the repeat body 

is processed. 

Example : 

ABC RPT ^ 
DATA 
ENDR 

This is equivalent to 

ABC DATA 

DATA 

DATA 

DATA 



An increment list has the form (s=«l[,e2]). . . (s*el[,e2]) 
where s stands for a symbol and el and e2 denote expressions 
(which must be absolute; undefined symbols are treated as if they 
were defined with the value -l). Before the repeat body is processed 
for .the first time, each symbol in the list is given the value of 
its associated el. Thereafter, each symbol is incremented by the 
value of its associated e2 just before the repeat body is processed. 
If e2 is missing, the value 1 is assumed. There is no limit on 
the number of elements that may appear in an increment list. 
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Example : 

RPT 3,(I=*0(J=0,-1) 

DATA I 

DATA J*I+1 
ENDR 

This results in code equivalent to the following: 



DATA 


k 




DATA 


0*^+1 


*l 


DATA 


5 




DATA 


-1*5+1 


~J* 


DATA 


6 




DATA 


-2*6+1 


=-11 



There is another format for RPT: 
[[$]label] RPT (s=el[,e2],e3)[ increment list] [comment] 
In this case, the number of times the repeat body is processed is 
determined by the construct (s=el[,e2],e3). This is the same as 
an increment list except that it includes a third expression 
(which must be absolute ; all undefined symbols are treated as if 
they were defined with the value -l), namely a bound on the value 
of the symbol. As soon as the bound is passed, processing of the 
repeat body stops. In the example above, the same effect could 
have been achieved by writing the head of the repeat statement as 

RPT (j=0,-l,-2Xl=i+) 
or as 

RPT (I=MXJ«=0,-1) 

Note that the bound does not have to be positive or greater than 
the initial value of the symbol being incremented; the algorithm 
for determining when the bound has been passed is given below. 

Occasionally one wishes to perform an indefinite number of 
repeats, terminating on an obscure condition determined in the 
course of the repeat operation. The conditional repeat directive, 
CRPT, serves this function. Its effect is like that of RPT (and 
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its repeat body is also closed off with an ENDR) except that instead 
of giving a number of repeats, its associated expression is evaluated 
just prior to each processing of the repeat body to determine 
whether to process the block. As for IP, > means true, < means 
false; the expression must be defined and absolute each time it is 
evaluated. The form is 

[[$]label] CRPT expression [, increment list] [comment] 

For example, one may write 

CRPT X>Y 
or 

CRPT STOP, (X=l, 2 ) ( Y=- 3 ) 

Note that the statement 

CRPT 10 

will cause an infinite number of repeats. 

The following flowcharts describe precisely the actions of 
the various repeat options: 

RPT expre ss ion [, increment list] 



skip the whole 
repeat block 




ito 




count : = value of expression 



yes 




no 



initialize symbols in increment 
list; evaluate all e2 expressions 

— I 



process the repeat body ^ 



• 



increment the symbols in 
the increment list 



count:: 



count -1 



yes 




count = 



no 



The el and e2 expressions 
are evaluated just once 
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yes 



^to\ 



RPT (S=el[,e2],e3)[increment list] 



Nstarj/ 



S:= el 



evaluate e2 and e3; 
initialize symbols in 
increment list; evaluate 
all e2 expressions. 



< 



All expressions are 
evaluated just once 




process the repeat block 



increment the symbols in 
the increment list 



S:* S+e2 
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CRPT 



expre ss ion [ , increment list ] 



.start 




initialize symbols in increment 
list; evaluate all e2 expressions; 



no 




evaluate expression £ 



"CT val 



value expression > 




yes 



process the repeat block 



increment the symbols in the increment 
list 



All el and e2 expressions 
are evaluated just once 



This expression is eval- 
uated over and over again 
and, of course, the values 
of the symbols in this 
expression may change from 
one evaluation to the next. 



The contents of a repeat body may contain any NARP code, in 
particular it may contain other repeat statements; the nesting of 
repeat statements may go to any level. 



5-9 



5.3 Introduction to macros 

On the simplest level a macro name may be thought of as an 
abbreviation or shorthand notation for one or more assembly- 
language statements. In this respect it is like an opcode in that 
an opcode is the name of a machine command and a macro name is 
the name of a sequence of assembly language statements. 

The 9*+0 has an instruction for skipping if the contents of 

a specified location are negative, but there is no instruction 

for skipping if the accumulator is negative. The instruction 

SKA (skip if memory and the accumulator do not compare ones) will 

serve when used with a cell whose contents mask off all but the sign 

bit. The meaning of SKA when used with such an operand is "skip 

if A is positive". Thus a programmer writes 

SKA =kB7 

BRU NEGCAS NEGATIVE CASE 

However, it is more than likely the case that the programmer 

wants to skip if the accumulator is negative, ^hen he must write 

SKA =UB7 

BRU *+2 

BRU POSCAS POSITIVE CASE 

Both of these situations are awkward in terms of assembly language 
programming . 

But we have in effect just developed simple conventions for 
doing the operations SKAP and SKAN (skip if accumulator positive 
or negative). Define these operations as macros: 

SKAP MACRO 

SKA =^B7 
ENBM 



SKAN MACRO 

SKA =^B7 
BRU *+2 
ENDM 



Now, more in keeping with the operations he had in mind, the 
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Programmer may write 

A22 SKAN 

BRU POSCAS 

The advantages of being able to use SKAP and SKAN should be 
apparent. The amount of code written in the course of a program 
is reduced; this in itself tends to reduce errors. A greater 
advantage is that SKAP and SKAN are more indicative of the action 
that the programmer had in mind, so that programs written in this 
way tend to be easier to read. Note, incidentally, that a label 
may be used in conjunction with a macro. Labels used in this way 
are usually treated like labels on instructions; they are assigned 
the current value of the location counter. This will be discussed 
in more detail later. 

Before discussing more complicated uses of macros, some 
additional vocabulary should be established. A macro is an 
arbitrary sequence of assembly language statements together 
with a symbolic name . During assembly, the macro is stored in an 
area of memory called the string storage . Macros are created 
(or, as is more frequently said, defined ) by giving a name and the 
associated sequence of statements. The name and the beginning 
of the sequence of statements are designated by the MACRO directive 
name MACRO 



ENDM 
The end of the sequence of statements is indicated by the ENDM 
directive . 

Refer to figure 1. When the assembler encounters a MACRO 
directive, switch B is thrown to position 1 so that the macro 
is simply copied into the string storage; note that the assembler 
does no normal processing but simply copies the source language. 
When the ENDM terminating the macro definition is encountered, 
switch B is put back to position and the assembler goes on 
processing as usual. 

It is possible that within a macro definition other definitions 
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Figure 1: Information Flow During Macro Processing 



SOURCE 
LANGUAGE 



BINARY 

MACHINE 

LANGUAGE 




A B 



1 

1 
1 1 



Effect 

normal assembly 
macro definition 
macro expansion 
macro definition during 
macro expansion 
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may be embedded. The macro defining machinery counts the 
occurrences of the MACRO directive and matches them against the 
occurrences of ENDM. Thus switch B is actually placed "back in 
position only when the ENDM matching the first MACRO is 
encountered. Therefore, MACRO and ENDM are opening and closing 
brackets around a segment of source language. Structures like 
the following are possible: 



name 1 
name 2 
name 3 

name k 
name 5 



MACRO — 
MACRO — 
MACRO -j 
ENDM — I 
MACRO-i 
ENDM-J 

endm 

MACRO H 
ENDM- — ' 
ENDM 



The utility of this structure will not be discussed here. Use 
of this feature of imbedded definitions should in fact be kept 
to a minimum since the implementation of this assembler is such 
that it uses large amounts of string storage in this case. What 
is important, however, is an understanding of when the various 
macros are defined. In particular, when name 1 is being defined, 
name 2, 3> etc., are not defined; they are merely copied into 
string storage. Name2, for example, will not be defined until 
namel is expanded. (it should be noted that macros, like 
opcodes, may be redefined.) 

The use of a macro name in the opcode field of a statement 
is referred to as a call . The assembler, upon encountering a macro 
call, moves switch A to position 1 (see figure l). Input to the 
assembler from the original source file temporarily stops and comes 
fnstead from string storage. During this period the macro is said 
to be undergoing expansion . It is clear that a macro must be 
defined before it is called. 

An expanding macro may include other macro calls, and these, 
in turn, may call still others. In fact, macros may even call 
themselves; this is called recursion . Examples of the recursive 
use of macros are given later. When a new macro expansion begins 
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within a macro expansion, information about the progress of 
the current expansion is saved. Successive macro calls cause 
similar information to be saved. At the end of each expansion 
the information about each previous expansion is restored. When 
the final expansion terminates, switch A is placed back in 
position 0, and input is again taken from the source file. 

Now let us carry our example one step further. One might 
argue that the action of skipping is itself awkward. It might 
be preferable to write macros BRAP and BRAN (branch to specified 
location if contents of accumulator are positive or negative). 
How is one to do this? The location to which the branch should 
go is not known when the macro is defined, in fact, different 
locations will be used from call to call. The macro processor, 
therefore, must enable the programmer to provide some of the 
information for the macro expansion at call time . This is done 
by permitting dummy arguments in macro definitions to be replaced 
by arguments (i.e., arbitrary substrings) supplied at call time. 
Each dummy argument is referred to in the macro definition by a 
subscripted symbol. This symbol or dummy name is given in the 
operand field of the MACRO directive. 

Let us define the macro BRAP: 

BRAP MACRO LABEL 
SKAN 

BRU LABEL(l) 
ENDM 

When called by the statement 'BRAP POSCAS*, the macro will 

expand to 

SKA =^B7 

BRU *+2 

BRU POSCAS 

Note that BRAP was defined in terms of another macro, SKAN. Also 
note that as defined BRAP was intended to take only one argument; 
other macros may use more than one argument. 
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The macro CBE (compare and branch if equal) takes two 
arguments. The first argument is the location of a cell to be 
compared for equality with the accumulator; the second is a 
branch location in case of equality. The definition is 

CBE 



MACRO 


D 


SKE 


D(l) 


BRU 


*+2 


BRU 


D(2) 


ENDM 





When CBE is called by the statement 

CBE =»21B,EQL0C 
the statements generated will be 



SKE 


=21B 


BRU 


*+2 


BRU 


EQLOC 



Note that in the macro call, the arguments are separated by 
commas . 

The following sections describe macro definitions and 
calls in more detail. 
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5.U MACRO, IMACRO, and ENDM Macro definition 

The form of a macro definition is: 
("MACRO -i 



name i or 

llMACROj 



[ dummy [ , generated, expre s s ion ] [ comment ] 



where name , generated , and dummy are all symbols, and expression 
is an expression. 

IMACRO is completely equivalent to MACRO except that if 
name is defined as a macro with MACRO the construct 

label name arguments 

will automatically cause label to be defined as the current 
value of the location counter, whereas if name were defined 
with LMACRO this automatic definition of label would not 
occur. 

Some details of the definition 

■^ generated appears, it should not be the same symbol 
as dummy , and neither of them should be "MACRO", "LMACRO", or 
"ENDM. " 

If name is already defined as an opcode, the old definition 
is completely replaced by the new. 

If the MACRO (or IMACRO) directive has no operand, then 
name is defined as an opcode that takes no operands. Otherwise, 
name becomes an opcode that may or may not take an operand. 

Whole-line comments (lines beginning with *) in the macro 
body are not saved in string storage as part of the macro 
definition, but comments following instructions are. Thus, it 
behooves the programmer to avoid the latter, as they eat 
string storage. 
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When a macro body is placed in string storage, superfluous 
blanks are removed. Thus, any contiguous string of blanks is 
compressed to one blank with the following exceptions: 

a) Blanks enclosed in single quotes (') are not compressed. 

b) Blanks enclosed in double quotes (") are not compressed. 

c) Blanks enclosed in parentheses are not compressed. In 
this use, the nesting of parentheses is taken into 
account, but a parenthesis between single or double 
quotes is not considered as part of the nesting 
structure . 

In most cases the programmer need not worry about these 
conventions, although there are times when he may get pinched. 
For example, if 

ASC iAxj.xBi 
appears in a macro definition, it will be expanded as 

ASC i<A x B$ 
To avoid such problems use 

ASC 'A^aB' 



5-17 



5.V.1 Dummy arguments 

The dummy argument specified as an operand of the MACRO 
directive may appear anywhere in the macro body, followed by a 
subscript. At call time the subscript is evaluated and its value 
is used to select the appropriate argument supplied in the call. 
Before describing the various kinds of dummy arguments a few 
conventions are needed: 

a) In the following, "argument" will refer to the character 
string as given in the macro call after possible enclosing 
parentheses have been removed (see section 5*6 for the 
format of argument strings). 

b) The number of arguments supplied by the call is n (n>0). 

c) The number of characters in argument ei is n(ei). 

d) The structure ei for i an integer stands for an expression. 
(However, its value stands for some argument usually, so 
ei will be used somewhat ambiguously to stand for an 
expression or the value of an expression.) The first 
argument in a call is numbered 1. 

e) The dummy argument is assumed to be "D". 

With the above in mind, we consider the three forms of dummy 
arguments: 

1) D(el) 

This expands to argument el (which may be the null string), where 
< el < n. (If el = then D(el) expands to the label field of 
the macro call; see section 5*6.) 
Special notation: D() = D(l) 

2) D(el,e2) 

If el > e2 then this expands to the null string (range of values 
of el and e2 is arbitrary), otherwise, this expands to argument 
el through e2, where < el < e2 < n, with each argument enclosed 
in parentheses and a comma inserted between each argument. For 
example, d(3,3) - (D(3)). 
Special notation: B(,) = D(l,n) 

D(,el) = D(l,el) 

D(el, ) = D(el,n) 
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3) D(el$e2,e3) 
In all cases, < el < n must be true. If e2 > e3 then this 
expands to the null string (range of values of e2 and e3 is 
arbitrary), otherwise, it expands to characters e2 through e3 
of argument el, counting the first character of an argument as 
character 1. If either e2 or e3 lies outside the argument, then 
the nearest boundary is chosen. To be more precise, before using 
e2 and e3 to select the piece of argument el that is desired, the 
following transformation is made: 

e2:= max (l,e2); e3:« max (l,e3); 

e2:s min (n(el), e2); e3:= min (n(el),e3); 

If argument el is the null string, then the dummy argument expands 
to the null string regardless of the values of e2 and e3. 
Special notations: 

D(el$,) = D(el$l, n(el)) = D(el) 

D(el$,e2) = D(el$l,e2) 

D(el$e2, ) =D(el$e2,n(el)) 

D(el$e2) = D(el$e2,e2) 

D(el$) = D(el$l) = D(el$l,l) 

In any of the six forms mentioned above, el may be missing; 

if so, 1 is assumed. E.g., D($) =* D(l$l,l). 
A general rule which will help in remembering what the special 
notations mean is the following: "Whenever an expression is 
missing from a form, the value 1 is assumed unless the expression 
is missing from a place where an upper bound is expected (as in 
D(3, ) or D(3$2, ), in which case the largest 'reasonable' value is 
assumed." 

In any of the above three cases, if an expression which 
designates an argument is out of range, then an error message is 
typed and argument is taken. 
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Following is an example of the various forms of dummy 
arguments : 

Macro definition: 



XAMPLE 


MACRO 


D 




B(2) 


D() D<0) 




ASC 


'D(2,U)' 




TEXT 


'V(k,)' D(-3,-k) NULL STRING 




ASC 


'J>te3,h)' 




ASC 


, D(2$-3,lB)' 




ENEM 




Macro call: 






BETA 


XAMPLE 


ALPHA, ADD, GAMMA , DELTA 



Macro expansion: 



BETA 



ADD 


ALPHA BETA 


ASC 


'(GAMMA), (DELTA) 1 


TEXT 


'(DELTA)' NULL STRING 


ASC 


'FH' 


ASC 


'ADD' 
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5 . h . 2 Gener ated symbols 

A macro should not, of course, have in its definition an 
instruction having a. label. Successive calls of the macro would 
produce a multiply-defined symbol. Sometimes, however, it is 
convenient to put a label on an instruction within a macro. 
There are at least two ways of doing this. The first involves 
transmitting the label as a macro argument when it is called. 
This is most reasonable in many cases; it is in fact often 
desirable so that the programmer can control the label being 
defined and can refer to it elsewhere in the program. 

However, situations do arise in which the label is used 
purely for reasons local to the macro and will not be referred 
to elsewhere. In cases like this it is desirable to allow for 
the automatic creation of labels so that the programmer is freed 
from worrying about this task. This may be done by means of the 
generated symbol . 

•k g ene ^ a ted symbol name may be declared when a macro is 
defined, specifying the name and the maximum number of generated 
symbols which will be encountered during an expansion. These 
two items follow the dummy symbol name given in the MACRO directive 
(as shown in section ^> ,k above) if the programmer wishes to use 
generated symbols in a macro. For example, 
MUMBLE MACRO D,G,*4- 
< macro body > 
ENDM 
might contain references to G(l), G(2), G(3) , and G(U), these 
being individual generated symbols. 

With regard to generated symbols the macro expansion machinery 
operates in the following fashion: A generated symbol base value 
for each macro is initialized to zero at the beginning of assembly. 
As each generated symbol is encountered, the expression constituting 
its subscript is evaluated. This value is added to the base 
value, and the sum is produced as a string of digits concatenated 
to the generated symbol name ; the first digit is always to 
reduce the likelihood of the generated symbol being identical to 
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a normal symbol defined elsewhere by the programmer. Thus, the 
first time MUMBLE is called, G(2) will be expanded as G02, G(U) 
as Gfto-, etc. 

At the end of a macro expansion, the generated symbol base 
value is incremented by the amount designated by the expression 
following the generated symbol name in the MACRO directive. This 
is k in the case of MUMBLE. Thus, the second call of MUMBLE will 
produce in place of G(2), G06, the third call will produce G010, 
etc. It should be clear that the generated symbol name should 
be kept as short as possible. 

The expression in the macro head (call it m) must have a 
value in the range [1,1023]. A generated symbol subscript must 
have a value in the range [l,m]. 
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5«^»3 Concatenation 

Occasionally, it is desirable to have a dummy argument follow 
immediately after an alphanumeric character, for example, to 
have D(l) follow just after ALPHA. But then the assembler 
would not recognize the dummy because it would see ALPHAD(l) 
instead of D(l). To get around this problem the concatenation 
symbol '.&' is introduced. Its sole purpose is to separate a 
dummy argument (or conceivably a generated symbol) from a preceding 
alphanumeric character during macro definition. Thus, the example 
becomes ALPHA. &D(l). The concatenation symbol is not stored in 
string storage so it does not appear during expansion. 

As an example, say that we wish to define a macro STORE, 
and suppose we have established the convention that certain 
temporary storage cells begin with the letters A, B, or X 
depending on what register is saved there. The definition is: 



STORE MACRO D 

ST.&D($) D(l) 
EMM 



If called by the statements 

STORE B17 
STORE Xkk 

the macro will expand as 

STB B17 
STX Xkh 



The concatenation symbol may appear anywhere in a macro 
definition, but it is only necessary in the case described above. 
If one macro is defined within another, any concatenation symbols 
within the inner macro will not be removed during the definition 
of the enclosing macro. 
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5.k.k Conversion of a value to a digit string 

As an adjunct to the automatic generation of symbols (or 

for any other purposes for which it may be suited) a capability 

is provided in the assembler's macro expansion machinery for 

conversion of the value of an expression at call time to a 

string of decimal digits. The construct 
($expression) 

will be replaced by a string of digits equal to the value of 

the expression. For example, if X=5 then 
AB($2*X+l) 

will be transformed into 
AB11 

If the value of the expression is zero then the digit string is 

f 0'; if it is negative then the digit string is preceded by a 

minus sign. 

This conversion scheme can also be used inside repeat blocks; 

for example 

RPT (1-1,10) 
TEMP($I) BSS 1 
ENDR 

creates 10 cells labelled TEMPI through TEMP10. 
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5.^.5 A note on subscripts 



The expressions used as subscripts for dummy arguments 
and generated symbols, as well as the expressions used in the 
conversion to a digit string must be absolute. Any undefined 
symbols appearing in these expressions are treated as if they 
were defined with the value -1. These expressions may themselves 
contain dummy arguments, generated symbols, and ($...), so 
constructs like ($^+D(l*D(3))) are possible. 
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5.5 NARG and NCHR Number of arguments and number of characters 

Macros are more useful if the number of arguments supplied 
at call time is not fixed. The precise meaning of a macro (and 
indeed, the result of its expansion) may depend on the number or 
arrangement of its arguments. In order to permit this, the 
macro undergoing expansion must "be able to determine at call time 
the number of arguments supplied. The NARG directive makes this 
possible. 

NARG functions like EQU except that no expression is used 
with it. Its form is 

[ $] symbol NARG [ comment ] 
The function of the directive is to equate the value of the symbol 
to the number of arguments supplied to the macro currently 
undergoing expansion. The symbol can then be used by itself or 
in expressions for any purpose. NARG may appear in any macro, 
even one which has no dummy argument (and thus never has any 
arguments at call time); it is an error for NARG to appear outside 
a macro. 

It is also useful to be able to determine at call time the 

number of characters in an argument. NCHR functions by equating 

the symbol in its label field to the number of characters in its 

operand field. Its form is 

[$] symbol NCHR [character string [comment]] 

where "character string" has exactly the same form as an argument 

supplied for a macro call, i.e., if it involves blanks, commas, 

or semi- colons it should be enclosed in parentheses (see section 

5.6). NCTR can appear anywhere, both inside and outside macros, 

but it is most useful in macros for determining the length of 

arguments. 

Examples : 

A NCHR ABCDPT A: =6 

B NCHR (,,XTZ,,,) B:=7 

C NCHR D(I) C:»? 
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5 .6 Macro calls 

The format of a macro call is : 

[[$]label] macroname [argstring] [comment] 

Such a call causes the macro whose name appears in the 
opcode field to be expanded, with the dummy arguments in the 
macro body replaced by the actual arguments of the argstring. 

The label field is always transmitted as argument 0, so 
that D(el), where el has value 0, is always legal inside a macro. 
An occurrence of D(el), where el=0, will be replaced by the 
label field. If the label field is empty, then D(el) expands 
to the null string. At most seven characters will be transmitted 
this way: the first six characters of the symbol in the label 
field, preceded by f $ T if the label field begins with '$'. 

If the user wishes to transmit an argument to a macro in 
the label field of the macro call, but does not wish to have 
the symbol in this field defined, he should define the macro 
with IMACRO rather than MACRO. (See section 5 A) An example: 





NT 


IMACRO 


D 






RPT 


D(l) 






DATA 


D(2) 






ENDR 






D(0) 


DATA 
ENDM 


-D(l 


when called by: 










DTE 


NT 


k,kB 


expands as: 












DATA 


i*B7 






DATA 


^B7 






DATA 


kwr 






DATA 


4B7 




DTE 


DATA 


-U 



Notice that this would have caused a doubly-defined symbol 
error had MACRO been used rather than IMACRO. 



5-27 



A macro call may or may not have an arg string (see section 
5-1+). If an arg string is present, it may contain any number 
of arguments, in fact, more than are referred to by the macro. 

Before describing an arg string, the following should be 
noted: blanks, commas, semi-colons, and parentheses that are 
enclosed in single or double quotes are treated exactly like 
ordinary characters enclosed in quotes; they do not serve as 
terminators, separators, delimiters, or the like. In effect, 
when the argument collector in NARP is collecting arguments 
for a macro call, the occurrence of a quote causes it to stop 
looking for special characters except for a matching quote (and, 
of course, carriage return, which is an absolute terminator). 
A single quote enclosed in double quotes is not a special 
character and vice versa. Thus, when a blank, comma, semi-colon, 
or parenthesis is referred to in the following, it is under- 
stood that it is not enclosed in quotes. 

An arg string for a macro call has the following format: 

<arg>,<arg>, . . . ,<arg> <terminator> 

where a terminator is a blank, semi-colon, or carriage return. 
There are three forms of <arg>: 

1. <arg> may be the null string. 

2. If the first character of <arg> is not a left paren- 
thesis then <arg> is a string of characters not con- 
taining blank, comma, semi-colon, or carriage return 
(remember that blanks, commas, and semi-colons may 
appear in <arg> if they are enclosed in quotes). 

3- If the first character of <arg> i£ a left parenthesis 
the <arg> does not terminate until a blank, comma, 
or semi-colon is encountered after the right parenthesis 
which matches the initial left parenthesis ("matches" 
means that all left and right parentheses in the 
argument are noted and paired off with each other so 
that a nested parentheses structure is possible). 
Of course, a carriage return at any point immediately 
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terminates <arg>. Again, remember that blanks, commas, 
semi-colons, and parentheses enclosed in quotes are 
ignored when <arg> is being delimited. The initial 
left parenthesis and its matching right parenthesis 
(which need not be the last character in <arg> ) are 
removed before <arg> is transmitted to the macro. 
Examples : 

mkC (>jl'>2S )> > ' HOUSE, JROGER' , (AB")") 

D(l) « 1jl5jl , 

D(2) = null string 

D(3) = ' HOUSE, ^ROGER' 

D(U) = AB M )" 

5 .7 Examples of conditional assembly and macros 

1. It is desired to have a pair of macros SAVE and RESTOR 

for saving and restoring active registers at the beginning and 

end of subroutines. These macros should take a variable number 

of arguments so that, for example, one can write 

SAVE A, SUBRS 
RESTOR A,B,X,SUBRS 

to generate the code 

STA SUBRSA 

LM SUBRSA 

LDB SUBRSB 

LDX SUBRSX 

To this end we first define a macro MOVE which is called 
by the same arguments delivered to SAVE and RESTOR, but with 
the string *ST ! or 'LD' appended. 



MOVE 


MACRO 


D 


X 


NARG 






RPT 


(Y=2,X-1) 




D(1)D(Y) 


D(X)D(Y) 




ENDR 






ENDM 





Now SAVE and RESTOR can be defined as 

SAVE MACRO D 

MOVE ST,D(,) 
ENDM 



5-29 



RESTOR 



MACRO 


D 


MOVE 


LD,D(,) 


ENDM 





2. Many programmers use flags, memory cells that nre 
used as binary indicators. The instruction SKN (skip if memory 
negative) makes it easy to test these flags if the convention is 
used that a flag is set (true) if it contains -1 and reset (false) 
if it contains 0. We want to define two macros, SET and RESET 
to manipulate these flags; furthermore, it is desirable to 
deliver at call time the name of an active register which will 
be used for the action. Calls of the macros will look like 

SET A,FLG1,FLG2,FLG3 
RESET X,FLG37,FLG12 

As in the previous example we make use of an intermediate 
macro, STORE, which takes the same arguments as SET and RESET. 



STORE 


MACRO 


D 


X 


NARG 






RPT 


(Y=2,X) 




ST.&D(l) 


D(Y) 




ENDR 






ENDM 




SET and RESET 


are defined 


as 


SET 


MACRO 


D 




LD.&D(1) 


=-1 




STORE 


D(,) 




ENDM 




RESET 


MACRO 
CL.&D(l) 


D 




STORE 


D(,) 




ENDM 





3. The following macro, MOVE, takes any number of pairs 
of arguments; the first argument of each pair is moved to the 
second, but an argument may itself be a pair of arguments, which 
may themselves be pairs of arguments, etc. MOVE extracts pairs of 
argument structures and transmits them to a second macro M0VE1. 



MOVE 
X 


MACRO 
NARG 


D 




RPT 


(Y=1,2,X) 




M0VE1 


D(Y),D(Y+1) 




ENDR 






ENDM 
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M0VE1 


MACRO 


G(l) 


NARG 


0(2) 


EQU 




IF 




LDA 




STA 




ELSE 




RFT 




M0VE1 




ENDR 




ENDF 




ENDM 



The main work is done in M0VE1 which calls itself recursively 
until it comes up with a single pair of arguments. 

D,G,2 

G(l)=2 

D(l) 
D(2) 

G(1)/2,(G(2)=G(2)+1) 
D(G(2)),D(G(2)4G(l)/2) 



When MOVE is called by 

MOVE A,B 

the code generated is 

LDA A 
STA B 

When called by 

MOVE A,B,C,D 

the code generated is 



When called by 



the code generated is 



LDA 


A 


STA 


B 


LDA 


C 


STA 


D 


MOVE 


(A,B),(C,D) 


is 




LDA 


A 


STA 


C 


LDA 


B 


STA 


D 



5-31 



And when called by 

MOVE ((A,B),(C,D)),((E,F),(G,H)) 
the code generated is 



LDA 


A 


STA 


E 


LDA 


B 


STA 


F 


LDA 


C 


STA 


G 


LDA 


D 


STA 


H 



It is instructive to trace the last example by hand to see how 
the recursive calls of M0VE1 work. This is an exercise left 
to the reader. 
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6.0 Operating NARP 

6.1 Error comments on statements 

When NARP encounters a statement which it deems incompre- 
hensible or illegal, it lists the statement in err or- format 
(corresponds to all listing format booleans being set) and then 
on the following line(s) lists all error comments pertaining 
to the statement. 

Most error-comments are as intelligible as the situation 
( and NARP's strangeness) allows. Some of the more common 
and/ or more obscure ones are listed and commented upon below: 



C ? The character C caught NARP unawares 

BAD (TERMINATION Premature termination, or garbage (like 

extraneous commas) where the statement 
should end. 

LC OVERFLOW The value of the location counter got 

out of the range [0, 37777 B] . 

DIRECTIVE OUTSIDE BODY And ENDF, ENDR, or ENCM without a 

matching IF, RPT, or MACRO. 

(symb) REDEFINED "symb" was defined (as a label) previous 

to this definition of it. 

(symb) OPCODE? "symb" was used as an opcode and is not 

in the opcode table. 

UNDEFINED EXPRESSION An undefined symbol occurs in an 

expression which should be defined. 



6.2 Other error comments 

If a fixed- length table ever flows, a message (name) 
OVERFLOW is printed (after a listing of the offending statement 
in error-format), followed by *****ASSEMBLY DEAD***** and 
termination of one assembly. 

The name may be; 

MAIN TABD5 Contains opcodes, literals, symbols 

(both undefined and defined). 

STRING STORAGE Contains MACRO definitions, macro calls 

and RPT expresions. 
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EXPRESSION TABLE 

INPUT POINTER STACK 
CHARACTER STACK 
OPERAND STACK 
PILE 



Contains post- fix Polish representations 
of expressions containing undefined 
symbols, until all the symbols in the 
expression are defined. 

Contains one entry for each embedded 
change of input- source. 

Holds the characters in a symbol while 
they are being collected. 

Holds operands in the processing of 
expressions . 

Space for temporaries in recursive calls 
of the expression eater. 



In addition, the following comments may appear: 



TRAP AT XXXXX 



1-0 ERROR 



NO END DIRECTIVE 



Error committed by NARP at location XXXXX; 
assembly terminates. 

Error in input or output of information, 
assembly terminates. 

An end- of- file encountered before an 
END directive; assembly will terminate 
as though an END directive was given 
(i.e., normally). 
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6.3 Starting an assembler 



Assuming that the user has entered the time -sharing system, 
NARP is called by hitting the rubout button until the exec 
answers (by typing f ^ f ) and then typing 'NARP 1 followed by a dot 
Control is then turned over to NARP and a source file must be 
specified; other information may also be supplied, if desired. 
The general format is: 

default convention 



©NARP. 






SOURCE FILE: 


file name 


none 


OBJECT FILE: 


file name 


none 


[TEXT FILE: 


file name] 


TELETYPE 



Each line above is either terminated by a dot or a semi-colon. 
A dot causes assembly to begin immediately (except after the 
source file name). The default conventions are used for all 
those options not explicitly specified. A semi-colon causes a 
carriage return to be typed, and the specification of some 
option is expected. 

The various options are discussed in more detail below: 
SOURCE FILE : As soon as NARP is started this line is typed and 
the user must specify a file containing a program 
to be assembled. When he terminates the name, 
NARP responds with 'OBJECT FILE:' on the next line 
OBJECT FILE: The file name given specifies where the binary 
output from the program should go. If the file 
name is terminated by a semi-colon, then a 
carriage return is typed and NARP waits for 
one of the following options to be specified. 
TEXT FILE: The file name given specifies where the listing 
of the source program and of the error messages 
should go. This option may be specified only once, 



A-l 



Appendix A; List of all pre-defined Placodes and pre-defined symbols 

The following table is a listing of an initialization program 
used to initialize the opcode table and symbol table of NARP. 
It will be noted that in some cases the OPD directive has four 
operands instead of the usual three; the fourth operand specifies 
the type (directive, macro, or instruction) of the opcode being 
defined. It is only possible to use four operands for OPD when 
NARP is being initialized, and once the initialization program 
has been assembled, OPD will only accept three operands. 



* ^ARP INITIALIZATION PROGRAM. 



(?1 NOV \96S) 



* OP? SYNTAX AMD SEMANTICS: 

* <SYf^POL> HPD <VALUE>[,<OP SIT >C , <SPIFTK >C , <TYPE>] ] ] 



* OPS IT > 



- OPERAND OPTIONAL 

1 - NO OPERAND 

? - OPFRAND REQUIRED 



* <SHIFTK 

* 



- NORMAL INSTRUCTION 

1 - SHIFT INSTRUCTION 



* <TYPE> 
* 



- INSTRUCTION 

1 - DIRECTIVE 

2 - MACRO 



* INSTRUCTION DEFINITIONS: 



LDA 


OPD 


STA 


nPD 


LDP 


OPD 


STB 


OPD 


LDX 


OPD 


STX 


OPD 


EAX 


npD 


X^A 


f, »PD 


ADC 


OPD 


ADC 


OPD 


AD *! 


OPD 


MIM 


OPD 


SUF 


rtpp 


sue 


OPD 


*UL 


OPD 


DIV 


opn 


FTP 


OPD 


y.p? 


OPD 


Fop 


OPD 


PCH 


OPD 


CLA 


OPD 


CLB 


OPD 


CLA* 5 


OPD 


CLX 


npD 


CLEAR 


">PD 


CAP 


npD 


CBA 


OPD 


XAB 


npn 


BAC 


npn 


A^C 


OPD 


CXA 


OPD 



07S00000B, 


>?■ 


LOAD A 


03500000B, 


>2 


STORE A 


07500000P, 


,2 


LOAD B 


03600000B, 


»2 


STORE B 


07100000B, 


.2 


LOAD X 


03700000B, 




STORE X 


07700000B 


,2 


COPY EFFECTIVE ADDRESS IN 


06200000B, 


r? 


EXCHANGE V. AND A 


05530051 OP 


,2 


ADD *i TO A 


05700000B 


»2 


ADD WITH CAPRY 


0S300000B 


>2 


ADD A TO M 


0S100000B 


>2 


tfE^ORY INCPEtfFNT 


O5 4 0O000B 


o 


SUBTRACT *! FROM A 


05 600000F- 


,2 


SUBTRACT WITH CARRY 


0S4 00 000B, 


>2 


MULTIPLY 


065 00 000B 


,2 


DIVIDE 


oi 400000P 


>?• 


EXTRACT (AND) 


01 600000B 


rt 


MEOGE (OR) 


01 700000B 


O 


EXCLUSIVE OR 


^4600000B, 


,2 


REGISTER CHANGE 


04 60000 IP 


, 1 


CLEAR A 


04<S0£002P 


, 1 


CLEAR P 


04S00003B, 


, 1 


CLEAR AB 


24600000B ( 


, 1 


CLEAR X 


P4600003E , 


, 1 


CLEAR A, B, AND X 


04600004B , 


, 1 


COPY A INTO B 


0A60001 0P , 


, 1 


COPY B INTO A 


0*60001 4B , 


, 1 


EXCHANGE A AMD P 


0/>S000 1?f , 


, 1 


COPY B INTO A, CLFAPING B 


714S00005R, 


1 


COPY A INTO R, CLEARING A. 


.Vi600?.00B , 


I 


COPY X INTO A 



|ax 


OPD 


XXA 


OPP 


CBX 


OPP 


CXF 


opp 


XXP 


opn 


ST r 


OPP 


LPF 


OPP 


X r ~ 


opp 


CNA 


OPP 


AXC 


OPP 


PFU 


OPP 


PFX 


OPO 


BR'M 


OPP 


PRP 


opp 


BFI 


opn 


SKS 


OPP 


SKF 


OPD 


SKG 


OPP 


SKP 


opn 


SK!" 


OPP 


SKM 


OPP 


SKA 


OPD 


SKF 


OPP 


?K^ 
I 


OPP 


f 

HSF 


OPP 


RCY 


opn 


LFSH 


OPD 


LSH 


OPP 


LCY 


opp 


NOD 


OPP 


HLT 


OPP 


ZRO 


OPP 


NOP 


OPD 


EXU 


OPD 


PPT1 


OPD 


BPT2 


OPP 


PPT3 


OPD 


PPT4 


OPD 


ROV 


OPP 


REO 


OPD 


OVT 


OPP 


OT~> 


OPD 


FIR 


OPP 


DIP 


OPP 


AIR 


WP 


( IBT 


OPP 


IDT 


OPP 



34 600 

04 600 
514 6013 

74 60 
04600 

4 600 

04600 

■2460! 

04600 



4 00B 
60 0B 
02 0p 
040B 

60F 
122B 
140R 

1 60B 

00B 
401P 



031 000 00P 
04100000E 
04300000P 
05 100000B 
01 100000B 

040.00080B 
05000000B 
07300000B 
06000000B 
07000000B 
05300000B 
07200000B 
05200000E 
07400000B 

06600000B 
06620000P 
06624000B 
06700000B 
06720000B 
06710300B 

00000000R 
00000000B 
02000000B 
02300000B 

04020400B 
04 020200B 
04020100B 
04020040P 

02200001B 

02200010B 
02200 10 IB 
02200 100B 

00220002B 
00220004B 
0022002 0B 
04020002B 
04 02 0004B 



2 
2 

2 
2 

2 

2 
2 
2 
2 
2 
2 
2 
2 
2 

2,1 
2,1 

2,1 
2,1 
2,1 
2,1 




2 



COPY A INTO X 
EXCHANGE X AND A 
COPY B INTO X 
COPY X H'TO B 
FXCHANGE X AND B 
STORE EXPONENT 
LOAD EXPONENT 
EXCHANGE EXPONENTS 
COPY NEGATIVE OF A 
COPY A TO X, CLEAR 



INTO 
A 



BRANCH UNCONDITIONALLY 

INCREMENT INDEX AND BRANCH 

NARK PLACE AND BRANCH 

RETURN BRANCH 

BRANCH AND RETUPN FRO* INTERRUPT 

SKIP IF SIGNAL NOT SET 

SKIP IF A EQUALS M 

SKIP IF A. GREATER THAN M 

REDUCE M, SKIP IF NEGATIVE 

SKIP IF A EQUALS W ON B *!ASK 

SKIP IF M NEGATIVE 

SKIP IF M AMD A DO MOT COMPARE ONE? 

SKIP IF M AND P DO NOT COMPARE ONES 

DIFFERENCE EXPONENTS AND SKIP 

RIGHT SHIFT AP 

RIGHT CYCLE AB 

LOGICAL RIGHT SHIFT AB 

LEFT SHIFT AB 

LEFT CYCLE AB 

NORMALIZE AND DECREMENT X 

HALT 

ZERO 

NO OPERATION 

EXECUTE 

BREAKPOINT TEST 1 
BREAKPOINT TEST 2 
BREAKPOINT TEST 3 
BREAKPOINT TEST 4 

RESET OVERFLOW 
RECORD EXPONENT OVERFLOW 
OVERFLOW TEST AND RESET 
OVERFLOW TEST ONLY 

ENABLE INTERRUPTS 
DISABLE INTERRUPTS 
API* /DISARM INTERRUPTS 
INTERRUPT ENABLED TEST 
INTERRUPT DISABLED TEST 



ALCW 
dtsv 

ASCV 

topv 

CAT''' 
CFTV 
C7TV 
C I T «•' 

F^n 

MIV 
VIM 
PIN 

POT 

P r T'^' 
BFTu? 

Bin 

BRS 

CIO 

CTRL 

DPI 

DPO 

DWI 

D>'0 

EXS 

FAD 

FPV 

FMP 

FS& 

GCD 

CCI 

ISC 

1ST 

LAS 

LDP 

ost 

SAS 

SBRM 

SPRR 

SIC 

SKSF 

SKSG 

STI 

Sjn 

SIP 
TCI 
TCO 
/CD 
WCH 
VCI 



OPD 
opd 
OPD 
OPD 

OPD 
Dpn 

OPD 

OPD 

OPD 

opo 

OPD 
OPD 
OPD 
OPD 
OPD 
OPD 

OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPP 
OPD 
OPD 
OPD 
OPD 
OPP 
OPD 
OPD 

OPD 
OPD 
OPD 
OPD 
opn 

OPD 
OPD 

OPD 

OPD 
npn 
npn 
npn 



00250 000P 
00200000B 

2*401 4000B 
0^01 1000R 

04 012000B 

04 010000P 

00600000P 
012000 00P 
03200003E 
0J300000B 
01300(*00B 
■Z0200000P 

040?0O1 ?IR 

57600000B 
57300000B 
56100000B 
57200000B 

5 42000.0 0B 
54300000B 
5 4400000P 
54500000R 
55200000B 
55600000B 
5 5300000E 
55A00000P 
55500000B 
5 3 700 00 0B 
5 6500000B 
54100000B 
55000000R 
5 4S00000B 
5 66000C10B 
55 100 00 0B 
5 4 700000B 
57000000B 
05140000B 
54000000B 
5 63 00 00 0B 
56200000B 
53630000B 
53 4 0000 ap 
5 6700000B 
5 74 00 000B 
5 75 00000B 
53500000B 
5 64 00 00 0B 
55700000B 



ALFRT CHANNFL W 

DISCONNECT CHANNFL V 

ALFRT TO STORE ADDRESS IM. CHANNEL 

TERMINATE OUTPUT ON CHANNEL V 



CHANNEL 
CHANNEL 
CHANNEL 
CHANNEL 

ENERGIZE 
M INTO V 
W BUFFER 
PARALLEL 
PARALLEL 
ENERGIZF 
W BUFFER 
W BUFFFR 



ACTIVE TEST 
W ERROR TEST 
W COUNT TEST 
W INTER-RECORD 



TEST 



OUTPUT D 
BUFFER WHEN 
INTO M WHEN 
INPUT 
OUTPUT 
OUTPUT M 
ERROR TEST 
READY TEST 



FMPTY 
FULL 



IN SYSTEM MODE 



BLOCK I/O 

BRANCH TO SYSTEM 

CHARACTER I/O 

CONTROL 

DRUM PLOCK INPUT 

DRUM BLOCK OUTPUT 

DRUM WORD INPUT 

DRUM WORD OUTPUT 

EXECUTE INSTRUCTION 

FLOATING ADD 

FLOATING DIVIDE 

FLOATING MULTIPLY 

FLOATING SUBTRACT 

GET CHARACTER AND DECREMENT 

GET CHARACTER AMD INCREMENT 

INTERNAL TO STRING CONV. (FLOATING OUTPUT 

INPUT FROM SPECIFIED TELETYPE 

LOAD FROM SECONDARY MEMORY 

LOAD POINTER (AB ) 

OUTPUT TO SPECIFIED TELETYPE 

STORE IN SECONDARY MFMORY 

SYSTEM PRM 

SYSTEM BRR 

STRING TO INTERNAL CONV. 

SKIP IF STRINGS EQUAL 

SKIP IF STRING GPEATER 

SIMULATF TELFTYPE INPUT 

STEAL TTY OUTPUT 

STORE POINTER (AB) 

TELETYPE CHARACTER INPUT 

TELETYPE CHARACTER OUTPUT 

WRITE CHARACTER AND DECREMENT 

WRITE CHARACTER 

WRITE CHARACTER AND INCREMENT 



(FLOATING INPUT) 



OPD 



5 6000000B,2 



WORD I/O 



* DIRECTIVE DEFINITIONS: 



ASC 

B r S 

BSS 

COPY 

CRPT 

DATA 

DEC 

DELSY* 1 

ELS r 

ELSF 

END 

ENDF 

ENDM 

FNDR 

FQU 

EXT 

FREEZE 

FFOT 

IDENT 

LIBEXT 
LIST 

MACRO 

NARG 

NCHR 

M OLIST 

OCT 

POPD 

R EL ORG 

RETREL 

RPT 

TEXT 

LMACRO 

RE* 

FROTOP 



OPO 
OPD 
OPD 
OPD 
OPD 
OPD 
nPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
DPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 
OPD 



q 


2, 


## 1 


l] 


>2, 


,0, 1 


2-1 


>2, 


0, 1 


3, 


► 2 


,0, 1 


4 


»2, 


,0, 1 


5, 


,2, 


,0,1 


7, 


> 1) 


, 1 


F, 


> 1 i 


,0,1 


9, 


.1, 


,55,1 


10, 


»2, 


0, 1 


1 ii 


>1) 


>?>, 1 


12, 


1, 


>0» 1 


13, 


r ! l 


0, 1 


14, 


>1< 


,21, 1 


15, 


>2, 


.0, 1 


16, 


»0! 


,0, 1 


17, 


1 If 


► <*, 1 


18, 


► 2, 


>0f 1 


19, 


>i< 


,0,1 


20, 


► 2, 


,0, 1 


25 


► 1) 


,0, 1 


21 


»0 


»0»1 


22 


► 


,0,1 


23, 


> 1* 


>3 f 1 


24, 


,0, 


,0, 1 


26 


,0, 


,0,1 


27, 


> It 


,0, 1 


2P, 


,2, 


► ^t 1 


29, 


>2 


»0| 1 


30, 


»1, 


► 0,1 


31, 


► 2, 


>flf 1 


32, 


► 2, 


,0, 1 


33, 


^5 


► 0, 1 


35, 


► 2, 


,0, 1 


37, 


»2, 


0, 1 



ASCII STRING 

BLOCK END SYMBOL 

BLOCK START SYMBOL 

REGISTER CHANGE 

CONDITIONAL REPEAT 

DATA WORD 

SET NUMBER RADIX TO 10 

DELETE SYMBOL 

ELSE 

ELSE IF 

END OF PROGRAM 

END IF 

END MACRO 

END REPEAT 

EQUATE 

EXTERNAL 

FREEZE TABLES 

FORGET SYMBOL 

IDENTIFICATION SYMBOL 

IF 

OUTPUT LABEL AS LIBRARY WYMBOL 

TURN ON LISTING 

MACRO DEFINITION 

NUMBER OF ARGUMENTS 

NUMBER OF CHARACTERS 

TURN OFF LISTING 

SET NUMBER RADIX TO « 

POP DEFINITION 

RELATIVE ORIGIN 

RETRIEVE ORIGIN 

REPEAT 

STRING (FOUR CHARACTERS P^R WORD) 

ALTERNATIVE MACRO DEF *N! 

PRINT REMARK ON TEXT FILE 

FORGET SELECTED OPCODES 



rZERO: EQU 
:LC? FQU 
FRGT 



* 

:ZERO: 

?ZFRO:,:LC 



FREEZE 
END 



LAST LINE OF NARP INITIALIZATION PROGRAM 
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Appendix B: Table of ASCII character set for the SDS 9^0 
octal value character octal value character octal value character 





I ! 
2 

3 # 

k $ 

5 « 

6 & 

7 

10 ( 

II ) 

12 * ; 

13 + 

1* 
15 
16 

17 / 

20 

21 1 

22 2 

23 3 
2k k 

25 5 

26 6 

27 7 



30 


8 


60 


P 


31 


9 


61 


Q 


32 


• 


62 


R 


33 


5 


63 


S 


3^ 


< 


6U 


T 


35 


= 


65 


U 


36 


> 


66 


V 


37 


9 


67 


W 


ko 


^-^ 


70 


X 


1+1 


A 


71 


Y 


k2 


B 


72 


Z 


k3 


C 


73 


[ 


kh 


D 


7^ 


\ 


h5 


E 


75 


1 


k6 


F 


76 


t 


hi 


G 


77 


«- 


50 


H 


135 


MULTIPLE BLANKS 


51 


I 


137 


END-OF-FILE 


52 


J 


Ikk 


END-OF-TAPE 


53 


K 


1^7 


BELL 


5^ 


L 


152 


LF 


55 


M 


15 1 * 


START NEW PAGE 


56 


N 


155 


CR 


57 










